---
created:
source_filename: /home/runner/work/mknodes/mknodes/mknodes/pages/mkclasspage/__init__.py
source_function: MkClassPage.__init__
source_line_no: 46
hide:
- toc
icon: material/image
template: SUMMARY.html
title: MkImage
---
[:fa-brands-github: Show source on GitHub](https://github.com/phil65/mknodes/blob/main/mknodes/basenodes/mkimage/__init__.py)
### Image including optional caption.
=== "Examples"
### Example: **With caption**
!!! jinja "Jinja"
``` {.jinja }
{{ "https://picsum.photos/200" | MkImage(caption="A caption!") }}
```
!!! python "Python"
``` {.python }
MkImage('https://picsum.photos/200', caption='A caption!')
```
===! "Rendered"

A caption!
=== "Markdown"
``` {.markdown }

A caption!
```
=== "Html"
``` {.html }
A caption!
```
=== "reST"
``` {.rst }
.. image:: https://picsum.photos/200
:alt: A caption!
```
=== "GitHub"
``` {.markdown }
```
### Example: **Right-aligned**
!!! jinja "Jinja"
``` {.jinja }
{{ "https://picsum.photos/200" | MkImage(align="right") }}
```
!!! python "Python"
``` {.python }
MkImage('https://picsum.photos/200', align='right')
```
===! "Rendered"
{ align=right }
=== "Markdown"
``` {.markdown }
{ align=right }
```
=== "Html"
``` {.html }
```
=== "reST"
``` {.rst }
.. image:: https://picsum.photos/200
:align: right
```
=== "GitHub"
``` {.markdown }
```
### Example: **Fixed width**
!!! jinja "Jinja"
``` {.jinja }
{{ "https://picsum.photos/200" | MkImage(width=500) }}
```
!!! python "Python"
``` {.python }
MkImage('https://picsum.photos/200', width=500)
```
===! "Rendered"
{ width="500" }
=== "Markdown"
``` {.markdown }
{ width="500" }
```
=== "Html"
``` {.html }
```
=== "reST"
``` {.rst }
.. image:: https://picsum.photos/200
:width: 500
```
=== "GitHub"
``` {.markdown }
```
### Example: **Hyperlinked**
!!! jinja "Jinja"
``` {.jinja }
{{ "https://picsum.photos/200" | MkImage(target="https://phil65.github.io/mknodes") }}
```
!!! python "Python"
``` {.python }
MkImage('https://picsum.photos/200', target='https://phil65.github.io/mknodes')
```
===! "Rendered"
[](https://phil65.github.io/mknodes)
=== "Markdown"
``` {.markdown }
[](https://phil65.github.io/mknodes)
```
=== "Html"
``` {.html }
```
=== "reST"
``` {.rst }
.. image:: https://picsum.photos/200
:target: https://phil65.github.io/mknodes
```
=== "GitHub"
``` {.markdown }
```
### Example: **Separate dark mode image**
!!! jinja "Jinja"
``` {.jinja }
{{ "https://picsum.photos/200" | MkImage(path_dark_mode="https://picsum.photos/300") }}
```
!!! python "Python"
``` {.python }
MkImage('https://picsum.photos/200', path_dark_mode='https://picsum.photos/300')
```
===! "Rendered"
 
=== "Markdown"
``` {.markdown }
 
```
=== "Html"
``` {.html }
```
=== "reST"
``` {.rst }
.. image:: https://picsum.photos/200
```
=== "GitHub"
``` {.markdown }
```
=== "DocStrings"
::: mknodes.MkImage
options:
show_docstring_description: False
=== "Sub classes"
| Name | Children | Inherits |
|--- | --- | --- |
| **[MkBinaryImage](https://phil65.github.io/mknodes/) ** *mknodes.basenodes.mkbinaryimage * Image carrying the data by itself\. | | [MkImage](https://phil65.github.io/mknodes/) |
| **[MkBadge](https://phil65.github.io/mknodes/) ** *mknodes.templatenodes.mkbadge * Node for a locally\-created badge \(based on "anybadge"\)\. | | [MkImage](https://phil65.github.io/mknodes/) |
=== "Base classes"
| Name | Children | Inherits |
|--- | --- | --- |
| **[MkNode](https://phil65.github.io/mknodes/) ** *mknodes.basenodes.mknode * Base class for everything which can be expressed as Markup\. | [MkContainer](https://phil65.github.io/mknodes/) [MkCompactAdmonition](https://phil65.github.io/mknodes/) [MkLink](https://phil65.github.io/mknodes/) [MkText](https://phil65.github.io/mknodes/) [MkHeader](https://phil65.github.io/mknodes/) [MkKeys](https://phil65.github.io/mknodes/) [MkDocStrings](https://phil65.github.io/mknodes/) [MkIcon](https://phil65.github.io/mknodes/) [MkImage](https://phil65.github.io/mknodes/) [MkProgressBar](https://phil65.github.io/mknodes/) [BaseBlock](https://phil65.github.io/mknodes/) ... | [Node](https://phil65.github.io/mknodes/) |
=== "⋔ Inheritance diagram"
``` mermaid
graph TD
94272696073872["mkimage.MkImage"]
94272697820320["mknode.MkNode"]
94272697777776["node.Node"]
139836355973312["builtins.object"]
94272697820320 --> 94272696073872
94272697777776 --> 94272697820320
139836355973312 --> 94272697777776
```
=== "NodeFile"
``` {.toml title='/home/runner/work/mknodes/mknodes/mknodes/basenodes/mkimage/metadata.toml'}
[metadata]
icon = "mdi:image"
name = "MkImage"
group = "image"
[examples.with_caption]
title = "With caption"
jinja = """
{{ "https://picsum.photos/200" | MkImage(caption="A caption!") }}
"""
[examples.right_aligned]
title = "Right-aligned"
jinja = """
{{ "https://picsum.photos/200" | MkImage(align="right") }}
"""
[examples.fixed_width]
title = "Fixed width"
jinja = """
{{ "https://picsum.photos/200" | MkImage(width=500) }}
"""
[examples.hyperlinked]
title = "Hyperlinked"
jinja = """
{{ "https://picsum.photos/200" | MkImage(target="https://phil65.github.io/mknodes") }}
"""
[examples.dark_mode_image]
title = "Separate dark mode image"
jinja = """
{{ "https://picsum.photos/200" | MkImage(path_dark_mode="https://picsum.photos/300") }}
"""
[fragments]
image = """
) ~ ")" ~ (node.align | add("{ align=", " }")) ~ (node.width | add('{ width="', '" }')) }}{% if node.lazy %}{ loading=lazy }{% endif %}
"""
linked_image = """
{% if node.url %}
[{{ "fragments/image" | render_template(node=node, path=path, mode=mode) }}]({{ node.url }}){% else %}
{{ "fragments/image" | render_template(node=node, path=path, mode=mode) }}{% endif %}
"""
[output.markdown]
template = """
{% if node.path_dark_mode %}
{% set link_dark = "fragments/linked_image" | render_template(node=node, path=node.path_dark_mode, mode="dark") %}
{% set link_light = "fragments/linked_image" | render_template(node=node, path=node.path, mode="light") %}
{% set markdown_link = link_dark ~ " " ~ link_light %}
{% else %}
{% set markdown_link = "fragments/linked_image" | render_template(node=node, path=node.path, mode=None) %}
{% endif %}
{% if node.caption %}
{{ markdown_link }}
{{ node.caption }}
{% else %}
{{ markdown_link }}{% endif %}
"""
[output.github]
template = """
{% if node.path_dark_mode %}
{% endif %}
"""
[output.rst]
template = """
.. image:: {{ node.path }}
{% if node.width %} :width: {{ node.width }}{% endif %}
{% if node.caption %} :alt: {{ node.caption }}{% endif %}
{% if node.align %} :align: {{ node.align }}{% endif %}
{% if node.url %} :target: {{ node.url }}{% endif %}
"""
```
=== "Code"
``` {.python title='mknodes.basenodes.mkimage.MkImage' linenums='18'}
class MkImage(mknode.MkNode):
"""Image including optional caption."""
ICON = "material/image"
ATTR_LIST_SEPARATOR = ""
def __init__(
self,
path: str,
*,
target: linkprovider.LinkableType | None = None,
caption: str = "",
title: str = "",
align: Literal["left", "right"] | None = None,
width: int | None = None,
lazy: bool = False,
path_dark_mode: str | None = None,
**kwargs: Any,
):
"""Constructor.
Args:
path: path of the image
target: Optional URL or node the image should link to
caption: Image caption
title: Image title
align: Image alignment
width: Image width in pixels
lazy: Whether to lazy-load image
path_dark_mode: Optional alternative image for dark mode
kwargs: Keyword arguments passed to parent
"""
super().__init__(**kwargs)
self.title = title
self.caption = caption
self.target = target
self.align = align
self.width = width
self.lazy = lazy
self._path_dark_mode = path_dark_mode
self._path = path
@property
def path(self) -> str:
if helpers.is_url(self._path):
return self._path
# TODO: linkreplacer doesnt work yet with full path
return pathlib.Path(self._path).name # this should not be needed.
@property
def path_dark_mode(self):
match self._path_dark_mode:
case str() if helpers.is_url(self._path_dark_mode):
return self._path_dark_mode
case str():
return pathlib.Path(self._path_dark_mode).name
case _:
return None
@property
def url(self) -> str:
return self.ctx.links.get_url(self.target) if self.target else ""
def _to_markdown(self) -> str:
if not self.path_dark_mode:
markdown_link = self._build(self.path)
else:
link_2 = self._build(self.path, "light")
link_1 = self._build(self.path_dark_mode, "dark")
markdown_link = f"{link_1} {link_2}"
if not self.caption:
return markdown_link
lines = [
"",
f" {markdown_link}",
f" {self.caption} ",
" ",
]
return "\n".join(lines) + "\n"
def _build(self, path, mode: Literal["light", "dark"] | None = None) -> str:
if mode:
path += f"#only-{mode}"
markdown_link = f""
if self.align:
markdown_link += f"{{ align={self.align} }}"
if self.width:
markdown_link += f'{{ width="{self.width}" }}'
if self.lazy:
markdown_link += "{ loading=lazy }"
if self.target:
markdown_link = f"[{markdown_link}]({self.url})"
return markdown_link
```